File sharing API integrations

The interface for the public API allows Workplace Super Administrators and Workplace Manager Team Administrators to perform administrative tasks for the webhooks integration, like setting up new integrations and viewing or managing the following:

• Enable/Disable - An on/off switch for each integration. When the integration is disabled, API calls will not be accepted by the service and webhook callbacks will not be received.

• Connection checking - A quick health check to see if the API integration you've configured is reachable over the Internet. Just go to the following screen (Configuration > Integrations > select API integration > click Check Connection) and wait for the results.

• Alerting - The public API contains an advanced alerting mechanism which helps administrators prevent outages and helps keep files in sync. The Workplace service proactively checks for error conditions and attempts to notify the relevant parties. By default, all team admins receive error notifications, but you can customize the recipients list.

There are four error conditions which could render the API non-functional:

• Missing share - This happens when the share created during the integration setup disappears and the integration can't access the files anymore. This can happen when the integration loses the share implicitly or explicitly. To fix this error, the share to the folder must be re-established. To identify the folder missing the share, the File API can be used:
  1. GET /webhooks
  2. GET /files/{folderId} - where folderId is the folderId from the previous call result

• Missing folder - This happens if the folder that is subscribed to is deleted from the service. To correct this error, either undelete the deleted folder or remove the webhooks via the API.

• Health check failure - The service sends health check messages to the registered endpoints at approximately five minute intervals. The endpoint must respect the client requirements, or it will raise health check alerts. Please make sure the registered endpoint responds correctly to health check messages. You can also use the connection checker screen in the integration detail to diagnose the problem.

• Retry failed - This alarm is raised when the service is not able to deliver an event to the appropriate endpoint after several attempts. When this error occurs, the integration enters a disabled state and will no longer function. To fix this issue, first confirm the endpoint's health and connectivity using the connection checker, then enable the integration. All queued messages should arrive at the endpoint when it is reenabled.

All message payloads are signed with the client secret key used for communication. The client can verify that the sender is the Workplace service. If the client secret is compromised, delete the integration immediately and configure a new one.

The signature algorithm is SHA-256.

Our in-app API documentation contains a wide variety of operations which can be performed on webhooks. Operations include, but are not limited to, getting a list of all webhooks, deleting all webhooks for given folder, getting information about about a webhook, deleting webhook, and creating a webhook for a given folder. To access the API documentation, click the Open API Documentation link located on a file sharing API tile. To access the API documentation, click this button:

NOTE  Kaseya Support cannot help you with the setup and configuration of custom API integrations, but we can help you make sure that your integration is operational.

NOTE  You can create multiple instances of the same file sharing integration to provide more granular control.

1. Access the client's Workplace Online with a Full Access or Team Access or team Administrator or Super Administrator account.
2. Go to Configuration > Integrations:
   
   
3. Click the + Add Integration button. The Add Integration popup window will open:
   
4. Click the API line item to select it.
5. Click the Add button. The Manage API Integration page will open:
   
6. Make an entry in the Integration Name field. The integration name will:

• identify this integration tile on the Integrations tab.
• be displayed when you share Workplace folders or projects to make them accessible to this integration.
• appear in report events that track changes made through this integration.

7. Optionally add a description of the integration in the Description field.
8. Click the Save button.
9. Copy the API information in the Endpoint URL, Client ID, and Client Secret fields to configure the service you want to integrate with Workplace.

IMPORTANT  If you need information concerning API operations or schemas, please click the Open API Documentation button at the top right of the page for comprehensive documentation of the Datto Workplace Public API.

10. Go to the projects and/or folders that you want to be able to access through this integration and create a team share for the integration.

NOTE  When you share a project or folder with an integration, click the icon and select the Integrations filter to find what you need faster.
For detailed instructions on how to share a project or folder with an integration, please refer to Share a project or folder.

NOTE  You may wish to add multiple instances of the same file sharing integration to create the potential for more more granular access control.

IMPORTANT  If the API integration does not function correctly, please refer to the Errors section, above.

About webhooks in Workplace

Webhooks provide an automated way for apps to remain in constant communication with each other. When apps are connected by webhooks, an event in one app can automatically trigger a communication to, and consequently an action within, another app.

Workplace webhooks allow you to automate workflow and build powerful integrations with third party services. They allow messages that are generated based on events that take place in the Workplace cloud to be relayed to a client's third party app. Basically, they're notifications about specific changes that have taken place in Workplace, like a new file upload or a folder deletion. You may, for example, wish to send an email, mark a task complete, or delete the stored file from another location.

EXAMPLE  Create a webhook in Workplace for a specific publicly shared folder for which share recipients have upload privileges, set to trigger when a file is uploaded. It then creates a task to review the uploaded item via the Microsoft Planner API.

For each event that's communicated from Workplace to the client, two components must be in place:

• A subscription from the client's third party app to the Workplace cloud event

• A notification, triggered by the event, sent from Workplace to the client's third party app

To configure a webhooks integration:

1. Set up the integration as described in Create a file sharing integration, above.

2. Refer to the API documentation for available webhooks functions. To access the API documentation, click this button:
   

NOTE  The POST command must be used with the folderID id of the folder you shared the integration with (use /file/{parentID}/files or /file/projects GET File API commands to get folderID), eventTypes for which you want to receive notifications and a callbackUrl.

3. When a command has been submitted and a response code of 200 has been received, the webhook has been successfully created. You can now get notifications for the subscribed folder.

IMPORTANT  If the API integration does not function correctly, please refer to the Errors section, above.

Additional considerations

Webhooks scope

All Workplace webhook registrations apply to a folder or a project. The scope of a webhook is a folder and all folders and files within it.

IMPORTANT  All children of the specified folder are subject to the webhook event trigger!

If a folder with a webhook registration is deleted, the service sends a folder.deleted event and an alert is generated.

API call structure

POST request body structure

All payloads for webhooks are in JSON format. Depending on the event type, the structure may vary, but in general it has a consistent structure containing 4 top-level objects:

• eventObject - describes the event which happened

• fileObject - describes the subject of the event - i.e. the file or folder which the event happened on.

• hookObject - describes a reference to the webhook object

• clientObject - describes the reference to the integration which generated the event

Example of payload

            {
  "eventObject": {
    "eventType": "folder.created",
    "eventTime": 1662537957444,
    "uuid": "6ac925d8-829c-44a6-a724-267c96009a91"
  },
  "fileObject": {
    "projectId": 29182813,
    "fileId": 29182815,
    "parentId": 29182813,
    "fileName": "meeting notes",
    "path": "/Registration StartUP"
    "pathById": "/29182813"
  },
  "hookObject": {
    "id": 80591
  },
  "clientObject": {
    "clientId": "9d03e9e3-555d-443e-85a6-4acef4ed9229"
  }
}  
        

NOTE  For more information, please check the API documentation accessible from the integration UI.

Webhooks Source IP addresses

All webhook requests coming from Datto Workplace will have one of the following source IP addresses depending on your team's geographical location:

Region	IP Addresses
US	162.142.88.10, 161.129.208.10, 161.129.222.10
Europe	77.233.251.134, 152.115.41.179
Canada	161.129.223.93, 161.129.210.70
Australia	103.109.131.4, 103.109.130.229

NOTE  For more infomation concerning IP addresses, please refer to Workplace ports and IP addresses.

Request signature

For security reasons, all webhook requests are signed with a SHA-1 checksum of the whole body payload.

The checksum value is stored in the HTTP header: x-body-signature-hmacsha1.

As noted above, the HMAC SHA-1 algorithm is used and the client secret associated with the integration represents the secret key. The byte array is converted into String, representing the hexadecimal values of each byte in order.

Example of body and corresponding value in header:

            {
  "eventObject": {
    "eventType": "folder.created",
    "eventTime": 1662537957444,
    "uuid": "6ac925d8-829c-44a6-a724-267c96009a91"
  },
  "fileObject": {
    "projectId": 29182813,
    "fileId": 29182815,
    "parentId": 29182813,
    "fileName": "meeting notes",
    "lut": 1662537957000,
    "path": "/Registration StartUP"
  },
  "hookObject": {
    "id": 80591
  },
  "clientObject": {
    "clientId": "9d03e9e3-555d-443e-85a6-4acef4ed9229"
  }
} 

 

Headers
connection	close
accept-encoding	gzip,deflate
user-agent	Apache-HttpClient/4.5.13 (Java/1.8.0_342)
host	webhook.site
content-length	363
x-body-signature-hmacsha1	c8dfea0108faf15430b6b261c9f09a9b954c88c5
from-server-id	1b
content-type	application/json  
        

Timing

The webhook request should be received within in a few milliseconds of the sync operation. Network speed may affect the speed with which the webhook request is received. The maximum delay may also be affected by the overall service load in the region and can take up to several seconds.

Request ordering

Webhook requests are generated in the same order as the corresponding sync operation occurred. For example, creating a folder and uploading a file into it should generate a webhook request with the event type “folder.created” first, then “file.created."

Request retries

A retry is a state in which the request encountered an issue while processing, and it was flagged to be processed again. There are two types of requests retries:

• Fast retry type- The issue occurred while processing the request from the Datto Workplace service.
  
  The response from the service must be delivered back to the Workplace service within five seconds. If it fails to be delivered in time \, the service will send the same webhook message three times within 30 seconds. If the third attempt fails, then the integration enters a warning state and all further processing is paused until a positive response is received.

• Slow retry type – The issue occurred while processing the request to the callback URL.
  If the response code from the callback URL is something other than "200" or when there is a request timeout for the callback URL (the request times out after five seconds), then the request is retried three times within 12 hours. After 12 hours the integration is disabled and an alert is raised.

Request limiting

This is not supported in the current version of this integration.

Client requirements

Response codes

For a webhook call to be considered complete from Workplace's perspective, HTTP 200 (OK) must be the response. Any other response is considered a failure to deliver the message and the message will be sent again.

Response timing

The response from the third party app must be delivered back to Datto Workplace service within five seconds. If it is not delivered in that timeframe, the "slow retry" mechanism is applied.

SSL

All webhook endpoints must present a valid TLS certificate to Datto Workplace, or the webhook calls will not be functional.